Add Sessions for Automatic Conversation History Management #752

knowsuchagency · 2025-05-24T06:26:07Z

Overview

This PR introduces Sessions, a new core feature addressing issue #745 that automatically maintains conversation history across multiple agent runs, eliminating the need to manually handle .to_input_list() between turns.

Key Features

🧠 Automatic Memory Management

Zero-effort conversation continuity: Agents automatically remember previous context without manual state management
Session-based organization: Each conversation is isolated by unique session IDs
Seamless integration: Works with existing Runner.run(), Runner.run_sync(), and Runner.run_streamed() methods

🔌 Extensible Session Protocol

Library-agnostic design: Clean protocol interface allows any storage backend
Drop-in implementations: Easy integration with Redis, PostgreSQL, MongoDB, or any custom storage
Production-ready interface: Async-first design with proper error handling and type safety
Vendor flexibility: Library authors can provide their own Session implementations

💾 Built-in SQLite Implementation

In-memory SQLite: Perfect for temporary conversations during development
Persistent SQLite: File-based storage for conversations that survive application restarts
Thread-safe operations: Production-ready with connection pooling and proper concurrency handling

🔧 Simple API

# Before: Manual conversation management
result1 = await Runner.run(agent, "What's the weather?")
new_input = result1.to_input_list() + [{"role": "user", "content": "How about tomorrow?"}]
result2 = await Runner.run(agent, new_input)

# After: Automatic with Sessions
session = SQLiteSession("user_123")

result1 = await Runner.run(agent, "What's the weather?", session=session)
result2 = await Runner.run(agent, "How about tomorrow?", session=session)  # Remembers context automatically

What's Included

Core Session Protocol

Session Protocol: Clean, async interface that any storage backend can implement
Type-safe design: Full type hints and runtime validation
Standard operations: get_messages(), add_messages(), pop_message(), clear_session()
Extensibility-first: Designed for third-party implementations

Reference Implementation

SQLiteSession Class: Production-ready SQLite implementation
Automatic schema management: Creates tables and indexes automatically
Connection pooling: Thread-safe operations with proper resource management
Flexible storage: In-memory or persistent file-based databases

Runner Integration

New session parameter: Drop-in addition to existing Runner methods
Backward compatibility: Zero breaking changes to existing code
Automatic history management: Prepends conversation history before each run

Session Protocol for Library Authors

The Session protocol provides a clean interface for implementing custom storage backends:

from agents.memory import Session
from typing import List

class MyCustomSession:
    """Custom session implementation following the Session protocol."""

    def __init__(self, session_id: str):
        self.session_id = session_id
        # Your initialization here

    async def get_messages(self, count: int | None = None) -> List[dict]:
        """Retrieve conversation history for this session."""
        # Your implementation here
        pass

    async def add_messages(self, messages: List[dict]) -> None:
        """Store new messages for this session."""
        # Your implementation here
        pass

    async def pop_message(self) -> dict | None:
        """Remove and return the most recent message from this session."""
        # Your implementation here
        pass

    async def clear_session(self) -> None:
        """Clear all messages for this session."""
        # Your implementation here
        pass

# Works seamlessly with any custom implementation
result = await Runner.run(agent, "Hello", session=MyCustomSession("session_123"))

Example Third-Party Implementations

# Redis-based session (hypothetical library implementation)
from redis_sessions import RedisSession
session = RedisSession("user_123", redis_url="redis://localhost:6379")

# PostgreSQL-based session (hypothetical library implementation) 
from postgres_sessions import PostgreSQLSession
session = PostgreSQLSession("user_123", connection_string="postgresql://...")

# Cloud-based session (hypothetical library implementation)
from cloud_sessions import CloudSession
session = CloudSession("user_123", api_key="...", region="us-east-1")

# All work identically with the Runner
result = await Runner.run(agent, "Hello", session=session)

Benefits

For Application Developers

Reduces boilerplate: No more manual .to_input_list() management
Prevents memory leaks: Automatic cleanup and organized storage
Easier debugging: Clear conversation history tracking
Flexible storage: Choose the right backend for your needs

For Library Authors

Clean integration: Simple protocol to implement for any storage backend
Type safety: Full type hints and runtime validation
Async-first: Modern async/await design throughout
Documentation: Comprehensive examples and API reference

For Applications

Better user experience: Seamless conversation continuity
Scalable architecture: Support for multiple concurrent conversations
Flexible deployment: In-memory for development, production storage for scale
Multi-agent support: Same conversation history can be shared across different agents

Usage Examples

Basic Usage with SQLiteSession

from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Assistant", instructions="Reply concisely.")
session = SQLiteSession("conversation_123")

# Conversation flows naturally
await Runner.run(agent, "Hi, I'm planning a trip to Japan", session=session)
await Runner.run(agent, "What's the best time to visit?", session=session)
await Runner.run(agent, "How about cherry blossom season?", session=session)

Multiple Sessions with Isolation

# Different users get separate conversation histories
session_alice = SQLiteSession("user_alice")
session_bob = SQLiteSession("user_bob")

# Completely isolated conversations
await Runner.run(agent, "I like pizza", session=session_alice)
await Runner.run(agent, "I like sushi", session=session_bob)

Persistent vs In-Memory Storage

# In-memory database (lost when process ends)
session = SQLiteSession("user_123")

# Persistent file-based database
session = SQLiteSession("user_123", "conversations.db")

Session Management Operations

session = SQLiteSession("user_123")

# Get all messages in a session
messages = await session.get_messages()

# Add new messages to a session
new_messages = [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"}
]
await session.add_messages(new_messages)

# Remove and return the most recent message (useful for corrections)
last_message = await session.pop_message()

# Clear all messages from a session
await session.clear_session()

Message Correction Pattern

# User wants to correct their last question
user_message = await session.pop_message()  # Remove user's question
assistant_message = await session.pop_message()  # Remove agent's response

# Ask a corrected question
result = await Runner.run(
    agent,
    "What's 2 + 3?",  # Corrected question
    session=session
)

Technical Details

Session Protocol Design

Async-first: All operations are async for non-blocking I/O
Type-safe: Full type hints with runtime validation
Error handling: Graceful degradation and detailed error messages
Resource management: Proper cleanup and connection handling

SQLiteSession Implementation

Thread-safe operations with connection pooling
Automatic schema management with proper indexing
JSON serialization for message storage
Memory-efficient conversation retrieval and storage
Cross-platform compatibility

Breaking Changes

None. This is a purely additive feature that doesn't affect existing functionality.

Documentation

Updated core concepts in docs/index.md to highlight Sessions as a key primitive
New comprehensive guide at docs/sessions.md with protocol implementation examples
Enhanced docs/running_agents.md with automatic vs manual conversation management
Full API reference integration via docs/ref/memory.md
Implementation guide for library authors

Sessions represent a significant architectural improvement for building conversational AI applications with the Agents SDK. The extensible Session protocol enables the ecosystem to provide specialized storage backends while maintaining a consistent, simple API for application developers.

## Summary - Introduced `SessionMemory` and `SQLiteSessionMemory` classes for automatic conversation history management. - Updated `Agent` class to support session memory configuration. - Enhanced `Runner` class to handle input preparation and result saving with session memory. - Added example demonstrating session memory usage. - Implemented tests for session memory functionality. ## Testing - `make format` - `make lint` - `make mypy` - `make tests`

- Added a check to raise a ValueError if `session_id` is not provided when session memory is enabled. - Updated the `SessionMemory` class to use a Protocol instead of an abstract base class, simplifying the implementation. - Modified tests to ensure an exception is raised when attempting to run with memory enabled but no session_id is provided.

- Introduced a section on creating custom memory implementations following the `SessionMemory` protocol. - Added code examples demonstrating how to implement and use a custom memory class. - Highlighted the requirement for `session_id` when session memory is enabled, with examples illustrating correct usage.

- Updated the Runner class to ensure that when memory=True, a single instance of SQLiteSessionMemory is created and reused across runs. - Added a test to verify that the same memory instance is returned for multiple calls when memory is enabled. - Ensured the agent stores the memory instance for consistency.

- Updated README and example scripts to utilize `SQLiteSessionMemory` explicitly instead of using a boolean flag for memory. - Modified `RunConfig` to accept a memory instance directly, enhancing clarity and flexibility in session management. - Adjusted tests to reflect the new memory handling approach, ensuring consistent behavior across different configurations.

- Updated `mkdocs.yml` to include `session_memory.md` in the documentation. - Enhanced `index.md` to highlight the new **Session Memory** feature for automatic conversation history management. - Modified `running_agents.md` to include details about the `memory` and `session_id` parameters in `RunConfig`. - Added comprehensive documentation for session memory functionality in the new `session_memory.md` file, including usage examples and best practices.

- Included `memory.md` in the documentation by updating `mkdocs.yml`. - Corrected links in `session_memory.md` to point to the appropriate memory classes. - Created a new `memory.md` file detailing the `SessionMemory` and `SQLiteSessionMemory` classes.

…essions and messages - Updated the constructor to accept `sessions_table` and `messages_table` parameters, allowing users to specify custom table names. - Modified SQL queries to utilize the provided table names, ensuring flexibility in database schema. - Adjusted index creation and deletion queries to reflect the new table name parameters.

- Implemented the `pop_message` method to remove and return the most recent message from a session. - Updated the `SessionMemory` protocol to include the new method signature. - Enhanced documentation in `session_memory.md` with examples demonstrating the usage of `pop_message`. - Added tests to verify the functionality of `pop_message`, including edge cases for empty sessions and multiple sessions.

- Converted synchronous database operations in `get_messages`, `add_messages`, `pop_message`, and `clear_session` methods to asynchronous using `asyncio.to_thread`. - Improved performance and responsiveness of the session memory handling by allowing non-blocking database interactions.

- Implemented a check in the Runner class to raise a ValueError if a session_id is provided without enabling memory in the RunConfig. - Updated tests to verify that the appropriate exception is raised when session_id is used without memory.

- Updated README, session_memory.md, and example scripts to remove the use of RunConfig for session memory configuration, directly passing memory and session_id parameters to the Runner.run method. - Enhanced clarity in documentation regarding the requirement of session_id when memory is enabled. - Adjusted tests to reflect the new approach, ensuring consistent behavior across different configurations.

- Introduced a new method `_init_db_for_connection` to handle database schema initialization for a specific connection. - Updated the `_init_db` method to call the new method, improving clarity and separation of concerns. - Added a comment to indicate the initialization of the database schema for the connection.

- Deleted the `_init_db` method as database schema initialization is now handled in `_init_db_for_connection`. - This change simplifies the class structure and improves clarity in the database connection management.

- Introduced a shared connection for in-memory databases to avoid thread isolation, improving concurrency. - Implemented a locking mechanism for database operations to ensure thread safety, regardless of the database type. - Updated the `_get_connection`, `_add_messages_sync`, `_pop_message_sync`, and `_clear_session_sync` methods to utilize the new locking and connection management logic.

- Added logic to initialize the database schema for file databases during connection setup. - Ensured that the schema is only initialized once, improving efficiency and clarity in connection management.

- Enhanced the error handling mechanism in the Runner class to ensure that exceptions during setup result in a completion sentinel being placed in the event queue. - Streamlined the input preparation process by consolidating the logic for handling session memory and updating the streamed result. - Improved clarity and maintainability of the code by restructuring the try-except blocks and ensuring proper resource management for spans and traces.

- Removed unused imports and streamlined the import statements for clarity and maintainability. - This change enhances the readability of the test file by focusing on the necessary components.

…clarity - Replaced `SQLiteSessionMemory` with `SQLiteSession` in the codebase, streamlining session management. - Updated documentation and examples to reflect the new session handling approach, removing the need for `session_id` when using sessions. - Enhanced the `Session` protocol to better define session behavior and improve consistency across implementations. - Adjusted tests to ensure compatibility with the new session structure, maintaining functionality across various scenarios.

- Renamed `session_memory.md` to `session.md` for clarity and consistency. - Updated links in `running_agents.md` to reflect the new documentation filename. - Added comprehensive documentation for session memory functionality, including usage examples and API reference. - Removed references to `SessionMemory` and `SQLiteSessionMemory` from the codebase to streamline session management.

- Changed all references from "Session Memory" to "Sessions" in README, documentation, and example files for consistency. - Updated descriptions to clarify the functionality of Sessions in managing conversation history across agent runs.

- Renamed instances of "session.md" to "sessions.md" in mkdocs.yml and running_agents.md for consistency. - Added new sessions.md file detailing the functionality and usage of session memory in the Agents SDK, including examples and API reference.

- Updated the `get_messages` method in the `Session` and `SQLiteSession` classes to accept an optional `amount` parameter, allowing retrieval of the latest N messages or all messages if not specified. - Added a demonstration in `session_example.py` to showcase the new functionality for fetching the latest messages. - Implemented tests in `test_session.py` to verify the behavior of the `get_messages` method with various amounts, ensuring correct message retrieval.

… environment

…tions" and clarify session implementation details. Adjusted section headers and descriptions for consistency with recent documentation updates.

norton120 · 2025-05-29T11:01:42Z

This seems like an obvious thing we should have. Maybe even extend this eventually to add simple rag to the session, that's more boilerplate I'd love not to have to build.

👍 ➕

rm-openai

This is a nice PR, simple interface. Going to have a couple more people weigh in as well. @damon-openai @dkundel-openai wdyt?

rm-openai · 2025-05-30T15:58:57Z

src/agents/memory/session.py

+
+
+@runtime_checkable
+class Session(Protocol):


nit, I prefer to use ABC instead, because it is better checked by type checkers, its is more readable (because it's clear when reading the code that the implementation is for a the interface). Also, isinstance checks are faster with ABC.

I would also go with ABC if it were meant only for internal use. The advantage of using Protocol is third-party implementations of our Session interface don't need to depend on openai-agents. We could even offer both -- a Session (Protocol) and SessionABC, with the protocol as the primary interface since ABCs automatically satisfy matching Protocols.

src/agents/memory/session.py

rm-openai · 2025-05-30T16:04:46Z

src/agents/memory/session.py

+        """
+        ...
+
+    async def pop_message(self) -> TResponseInputItem | None:


what the usecase for popping messages?

It would be useful for making edits to the last user message or generating a new assistant response to the last user message.

dkundel-openai · 2025-05-30T16:14:13Z

I like the overall concept and design. Only concern on my side would be confusion if someone passes both a session and an array of inputs (as opposed to just a string like in the examples).
But supportive of this

knowsuchagency · 2025-05-31T04:22:52Z

That's an excellent point @dkundel-openai. I think it's better to raise an exception if a user tries passing both a list and a session. It would be confusing whether the list input should be appended to the existing session or replace it entirely. I'd rather be forced to choose between the two as a user.

- Updated the `get_messages` method in the `Session` and `SQLiteSession` classes to use 'count' instead of 'amount' for clarity. - Adjusted the corresponding example in `session_example.py` to reflect this change. - Modified tests in `test_session.py` to ensure they reference the new 'count' parameter.

…on memory functionality. This cleanup improves code maintainability and focuses on the current testing approach.

…n Runner class - Added a check in the Runner class to raise a UserError when both a session and a list input are provided, clarifying the expected input format. - Introduced a new test in test_session.py to ensure that this validation works correctly across different runner methods.

- Added `SessionABC` as an abstract base class for session implementations, providing a clear structure for managing conversation history. - Defined abstract methods for message retrieval, addition, and session management, ensuring consistency across implementations. - Updated `SQLiteSession` to inherit from `SessionABC`, aligning with the new architecture.

Resolved conflicts in src/agents/run.py: - Kept both UserError and RunErrorDetails imports - Preserved session functionality (_prepare_input_with_session and _save_result_to_session) - Integrated upstream's RunErrorDetails exception handling - Maintained max turns check logic while incorporating upstream changes

knowsuchagency · 2025-05-31T05:59:51Z

I made it so using a session with list input raises an exception. There's a test to verify the exception gets raised.

knowsuchagency added 9 commits May 23, 2025 22:13

revert changes to Agent. memory is a concern of the runner

14edb3c

knowsuchagency mentioned this pull request May 24, 2025

Add Session Memory #745

Open

knowsuchagency marked this pull request as draft May 24, 2025 06:35

knowsuchagency added 10 commits May 24, 2025 10:39

Remove redundant database initialization method in SQLiteSessionMemory

764e82c

- Deleted the `_init_db` method as database schema initialization is now handled in `_init_db_for_connection`. - This change simplifies the class structure and improves clarity in the database connection management.

Initialize database schema for file databases in SQLiteSessionMemory

131c5dc

- Added logic to initialize the database schema for file databases during connection setup. - Ensured that the schema is only initialized once, improving efficiency and clarity in connection management.

Refactor test_session_memory.py to simplify imports

8b827f2

- Removed unused imports and streamlined the import statements for clarity and maintainability. - This change enhances the readability of the test file by focusing on the necessary components.

knowsuchagency marked this pull request as ready for review May 24, 2025 21:37

knowsuchagency added 7 commits May 24, 2025 15:45

Update AGENTS.md to include note on executing CLI commands in virtual…

b5ad785

… environment

Update README to reflect changes from "Memory options" to "Session op…

e26aed1

…tions" and clarify session implementation details. Adjusted section headers and descriptions for consistency with recent documentation updates.

knowsuchagency changed the title ~~Add Session Memory for Automatic Conversation History Management~~ Add Sessions for Automatic Conversation History Management May 25, 2025

rm-openai reviewed May 30, 2025

View reviewed changes

knowsuchagency added 6 commits May 30, 2025 21:51

Add .claude/settings.local.json to .gitignore

51be95c

Remove original non-parametrized tests from test_session.py for sessi…

e661e78

…on memory functionality. This cleanup improves code maintainability and focuses on the current testing approach.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Sessions for Automatic Conversation History Management #752

Add Sessions for Automatic Conversation History Management #752

knowsuchagency commented May 24, 2025 •

edited

Loading

Uh oh!

norton120 commented May 29, 2025

Uh oh!

rm-openai left a comment

Uh oh!

rm-openai May 30, 2025

Uh oh!

knowsuchagency May 31, 2025

Uh oh!

Uh oh!

rm-openai May 30, 2025

Uh oh!

knowsuchagency May 31, 2025

Uh oh!

dkundel-openai commented May 30, 2025

Uh oh!

knowsuchagency commented May 31, 2025

Uh oh!

knowsuchagency commented May 31, 2025

Uh oh!

Uh oh!

Add Sessions for Automatic Conversation History Management #752

Are you sure you want to change the base?

Add Sessions for Automatic Conversation History Management #752

Conversation

knowsuchagency commented May 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Features

🧠 Automatic Memory Management

🔌 Extensible Session Protocol

💾 Built-in SQLite Implementation

🔧 Simple API

What's Included

Core Session Protocol

Reference Implementation

Runner Integration

Session Protocol for Library Authors

Example Third-Party Implementations

Benefits

For Application Developers

For Library Authors

For Applications

Usage Examples

Basic Usage with SQLiteSession

Multiple Sessions with Isolation

Persistent vs In-Memory Storage

Session Management Operations

Message Correction Pattern

Technical Details

Session Protocol Design

SQLiteSession Implementation

Breaking Changes

Documentation

Uh oh!

norton120 commented May 29, 2025

Uh oh!

rm-openai left a comment

Choose a reason for hiding this comment

Uh oh!

rm-openai May 30, 2025

Choose a reason for hiding this comment

Uh oh!

knowsuchagency May 31, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rm-openai May 30, 2025

Choose a reason for hiding this comment

Uh oh!

knowsuchagency May 31, 2025

Choose a reason for hiding this comment

Uh oh!

dkundel-openai commented May 30, 2025

Uh oh!

knowsuchagency commented May 31, 2025

Uh oh!

knowsuchagency commented May 31, 2025

Uh oh!

Uh oh!

knowsuchagency commented May 24, 2025 •

edited

Loading